.so ../bk-macros
.TH "bk url" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk url \- methods of accessing \*[BK] repositories
.SH DESCRIPTION
\*[BK] supports many ways to access a repository.  The selection of the
access method is determined by how the repository is referenced.  Each
reference form is described below with an explanation of how the repository
is accessed following each form.
.LP
In all cases below if the
.ARG pathname
part of the URL starts with a \*(lq/\*(rq then the pathname is absolute,
otherwise it is relative to the location of the bkd.
If
.ARG pathname
is not set then the implied remote directory must be the root of a 
repository.
See EXAMPLES below.
.SH ACCESS METHODS
.SS LOCAL
.in +4
.de head
.	br
.	ne 4
.	ti -4
..
.head
.ARG pathname
.head
\fBfile\fR://\c
.ARG pathname
.br
Access is all local, through the local file system.
.SS RSH
.in +4
.head
\fBrsh\fR://\c
.ARGc host /
.ARG pathname
.br
.head
\fBrsh\fR://\c
.ARGc user @
.ARGc host /
.ARG pathname
.br
Uses
.B rsh
to access
.ARG host 
and starts in the user's home directory.
.SS SSH
.in +4
.head
.ARGc host :
.ARG pathname
.br
.head
.ARGc user @
.ARGc host :
.ARG pathname
.br
Uses 
.B ssh 
(by default)
to access 
.ARG host 
and starts in the user's home directory.
If 
.V $BK_RSH 
is set, then that is used to talk to the host (allows for proxying).
If no 
.B ssh
is found then falls back to
.BR rsh .
.head
\fBssh\fR://\c
.ARGc host /
.ARG pathname
.br
.head
\fBssh\fR://\c
.ARGc host :
.ARGc port /
.ARG pathname
.br
.head
\fBssh\fR://\c
.ARGc user @
.ARGc host /
.ARG pathname
.br
.head
\fBssh\fR://\c
.ARGc user @
.ARGc host :
.ARGc port /
.ARG pathname
.br
Uses
.B ssh
to access
.ARG host 
and starts in the user's home directory.
.head
\fBbk\fR://\c
.ARGc user @
.ARGc host /
.ARG pathname
.br
This is a deprecated form of
.B ssh
that only worked with a
.B bkd
run as a login shell.
Connecting to a
.B bkd
running as a login shell is still supported.
Please use the
\fBssh\fR://
URL form.
.\" XXX - remember to mention turning off remote when we get to 3.3.x
.SS BKD
.in +4
.head
\fBbk\fR://\c
.ARGc host /
.ARG pathname
.br
Connects to an existing 
.B bkd
on the default 
.B bkd
port
and starts in the directory where the long lived
.B bkd
was initially started.
.head
\fBbk\fR://\c
.ARGc host :
.ARGc port /
.ARG pathname
.br
Connects to an existing 
.B bkd
on the specified port
and starts in the directory where the long lived
.B bkd
was initially started.
.SS HTTP
.in +4
.head
\fBhttp\fR://\c
.ARGc host /
.ARG pathname
.br
Connects to an existing 
.B bkd
using the HTTP port and transfer protocol
and starts in the directory where the long lived
.B bkd
was initially started.
.head
\fBhttp\fR://\c
.ARGc host :
.ARGc port /
.ARG pathname
.br
Connects to the specified port 
using the HTTP transfer protocol
and starts in the directory where the long lived
.B bkd
was initially started.
.SH PROXIES
.LP
\*[BK] supports most HTTP proxies.  Information about proxies needs to be
passed to \*[BK] in the environment.
.LP
The following are the environmental variables are available for use:
.br
.RS .4i
.Bc http_proxy= 
.Bc http://
.ARGc host :
.ARG port
.br
.Bc http_proxy=
.Bc http://[
.ARGc user :
.ARGc pass @]
.ARGc host :
.ARG port /
.br
.Bc no_proxy=
.ARG comma,separated,list,of,hosts,to,not,proxy
.LP
.V SOCKS_HOST =\c
.ARG host_name
.br
.V SOCKS_PORT =\c
.ARG port_number
.br
.V SOCKS_SERVER =\c
.ARGc host :
.ARG port
.RE
.LP
.B Note:
if
.V SOCKS_HOST
is set,
.V SOCK_PORT
must also be set.
If you are not sure if you should set environment variables, please consult
your system administrator.
.LP
On Windows, \*[BK] will also read
.B Internet Explorer's
proxy information from the registry.
So in most cases if Internet Explorer can browse the web then
\*[BK] will work as well.
.SH EXAMPLES
To clone 
.ARG old
to 
.ARG new :
.DS
bk clone old new
.DE
To clone from a repository named 
.ARG old
on a host named
.ARG host 
using SSH:
.DS
bk clone ssh://host/old new
.DE
To clone from a repository named 
.ARG old
on a host named
.ARG host 
using rsh:
.DS
bk clone rsh://host/old new
.DE
To clone from a repository named 
.B /home/bk/mysql
on a host named
.ARG host 
using ssh (note there are 2 slashes before \*(lqhome\*(rq):
.DS
bk clone ssh://host//home/bk/mysql new
.DE
Suppose that you had a number of repositories in 
.B /home/bk 
and you wanted to make them available via the bkd protocol.  
On the server you would run:
.DS
cd /home/bk
bk bkd
.DE
and on the client you would run this to get 
.BR /home/bk/mysql :
.DS
bk clone bk://server/mysql
.DE
.\" help://remote
.\" help://naming
.SH SEE ALSO
.SA bkd
.SH CATEGORY
.B Repository
.br
.B Overview
